---
order: 5.1
category: '@threlte/extras'
sourcePath: 'packages/extras/src/lib/components/AnimatedSpriteMaterial/AnimatedSpriteMaterial.svelte'
title: <AnimatedSpriteMaterial>
type: 'component'
componentSignature:
  {
    props:
      [
        {
          name: 'textureUrl',
          type: 'string',
          required: true,
          description: 'The URL of the spritesheet texture image.'
        },
        {
          name: 'dataUrl',
          type: 'string',
          required: false,
          description: 'The URL of the spritesheet JSON.'
        },
        {
          name: 'animation',
          type: 'string',
          required: false,
          description: 'The current playing animation name.'
        },
        {
          name: 'loop',
          type: 'boolean',
          required: false,
          default: 'true',
          description: 'Whether or not the current animation should loop.'
        },
        {
          name: 'autoplay',
          type: 'boolean',
          required: false,
          default: 'true',
          description: 'Controls whether or not to automatically run an animation on load.'
        },
        {
          name: 'fps',
          type: 'boolean',
          required: false,
          default: '10',
          description: 'The desired frames per second of the animation.'
        },
        {
          name: 'filter',
          type: '"nearest" | "linear"',
          required: false,
          default: '"nearest"',
          description: 'The texture filtering applied to the spritesheet.'
        },
        {
          name: 'alphaTest',
          type: 'number',
          required: false,
          default: '0.1',
          description: 'Sets the alpha value to be used when running an alpha test.'
        },
        {
          name: 'delay',
          type: 'number',
          required: false,
          default: '0',
          description: 'Delay the start of the animation in ms.'
        },
        {
          name: 'transparent',
          type: 'boolean',
          required: false,
          default: 'true',
          description: 'Whether or not the material should be transparent.'
        },
        {
          name: 'flipX',
          type: 'boolean',
          required: false,
          default: 'false',
          description: 'Whether or not the Sprite should flip sides on the x-axis.'
        },

        {
          name: 'totalFrames',
          type: 'number',
          required: false,
          default: 'rows * columns - 1',
          description: 'The total number of frames in the spritesheet.'
        },
        {
          name: 'startFrame',
          type: 'number',
          required: false,
          default: '0',
          description: 'The start frame of the current animation.'
        },
        {
          name: 'endFrame',
          type: 'number',
          required: false,
          default: 'totalFrames',
          description: 'The end frame of the current animation.'
        },
        {
          name: 'rows',
          type: 'number',
          required: false,
          default: '1',
          description: 'The number of rows in the spritesheet.'
        },
        {
          name: 'columns',
          type: 'number',
          required: false,
          description: 'The number of columns in the spritesheet.'
        }
      ],
    events:
      [
        { name: 'load', payload: 'void', description: 'Fires when all resources have loaded.' },
        { name: 'start', payload: 'void', description: 'Fires when an animation starts.' },
        { name: 'end', payload: 'void', description: 'Fires when an animation ends.' },
        { name: 'loop', payload: 'void', description: 'Fires when an animation loop completes.' }
      ],
    exports: [{ name: play, type: '() => void' }, { name: pause, type: '() => void' }]
  }
---

Provides animation tools for spritesheets.

<Example path="extras/animated-sprite-material" />

This material is most easily used by passing it a [spritesheet](https://www.aseprite.org/docs/sprite-sheet/) URL and a [JSON metadata file](https://gist.github.com/dacap/db18e5747a4b6e208d3c) URL.

Currently, JSON metadata using [Aseprite's](https://www.aseprite.org/) [hash export format](https://www.aseprite.org/docs/cli/#data) is supported.

Animation names [from tags](https://www.aseprite.org/docs/tags) can be used to transition to specific animations in the spritesheet.

```svelte {4,5}+
<T.Sprite>
  <AnimatedSpriteMaterial
    animation="Idle"
    textureUrl="./player.png"
    dataUrl="./player.json"
  />
</T.Sprite>
```

If no metadata file is provided, additional props must be passed to run an animation:

- `totalFrames`, if the spritesheet is only a single row.
- `totalFrames`, `rows`, and `columns`, otherwise.

```svelte {4-6}+
<T.Sprite>
  <AnimatedSpriteMaterial
    textureUrl="./fire.png"
    totalFrames={14}
    rows={4}
    columns={4}
  />
</T.Sprite>
```

Additionally, if a sheet with no JSON supplied has multiple animations, start and end frames must be passed to run an animation within the sheet.

```svelte {7-8}+
<T.Sprite>
  <AnimatedSpriteMaterial
    textureUrl="./fire.png"
    totalFrames={14}
    rows={4}
    columns={4}
    startFrame={4}
    endFrame={8}
  />
</T.Sprite>
```

`<AnimatedSpriteMaterial>` can be attached to a `<T.Sprite>` as well as a `<T.Mesh>`.

<Example path="extras/animated-sprite-mesh" />

In the case of a `Mesh` parent a `MeshBasicMaterial` will be used by default, instead of a `SpriteMaterial` when attached to a `Sprite`. A custom depth material will be attached when parented to a mesh to support shadows.

Any other material type can be used as well.

```svelte {3}+
<T.Mesh>
  <AnimatedSpriteMaterial
    is={THREE.MeshStandardMaterial}
    textureUrl="./fire.png"
    totalFrames={14}
  />
</T.Mesh>
```
